TRUCKER RADIO - PLAYER AGENT PROTOCOL  (v0.4)
All players (PC, phone app, future Android/iPhone/Pi/media center) talk to the
server the same way. No login is needed for any of this (client_open = true).

Base URL:  https://radio.electro-works.com     (no port, no IP)
           http://radio.electro-works.com       (if https is not bound yet)
           http://172.16.100.250:6969           (LAN fallback, when the router has no NAT loopback)
Try them in that order; use the first one that answers GET /api/nowplaying.
Follow redirects (http -> https).

1. LISTEN
   GET /stream                 audio/mpeg, 192 kbps MP3, endless
     Request header  Icy-MetaData: 1  -> server sends icy-metaint: 16000 and
     StreamTitle='Artist - Title' blocks (standard Shoutcast/Icecast format).
     Title markers are sent in-band at the point the new song starts, so update
     the screen when that audio is PLAYED, not when it is downloaded.
   Optional header:  X-Agent-Name: "Android - John's phone"   (shows in the listener log)
   Only if the station owner sets stream_password: ?key=<password> or HTTP Basic auth.
   Any HTTP/Icecast player works (VLC, Kodi, Winamp, ExoPlayer, AVPlayer).
   GET /stream?from=song       (0.7.1) start at the newest song's FIRST NOTE instead of the 3 s burst - used right
     after a skip (see 4), so the seconds of the old song still in your buffer are thrown away. Served while the song
     is under ~20 s old; later it is the normal burst. Not counted as a new tune-in on the console.
   STANDBY (0.7.1): when nobody has listened for 2 min the station finishes the song and waits. Connecting wakes it:
     the waiting song starts from its first note and the first ~3 s arrive at once, so playback starts right away.

2. NOW PLAYING
   GET /api/nowplaying  ->
   { "now":  {id, artist, title, album, year, genre, deck, source, started, position, length, ...},
     "next": {id, artist, title, source},
     "history": [ {id, artist, title, album, year, deck, ts}, ... newest first ],
     "playing": true|false, "standby": true|false, "listeners": n, "station": "...", "server_time": epoch }
   Optional request header (0.7.1)  X-Agent-Timing: skip=1.8;start=1.1  - seconds from pressing Next (skip) / Play
     (start) until the new song was actually PLAYING here. Shown in the console's Stats for nerds.
   You hear the station a few seconds late: match the ICY title (or
   server_time - your buffer) against now + history to get the song id you HEAR.

3. ALBUM ART
   GET /api/art/<id>   image/jpeg|png; the station logo when the song has none
   (header X-Placeholder: 1).

4. NEXT (skip)
   POST /api/skip   Content-Type: application/json   {"song_id": <id you are hearing>}
   Header X-Agent-Name. (X-Agent-Key only if the owner turns client_open off.)
   Server fades the song out and starts the next deck. A listener's skip is quick (0.7 s fade) and a long DJ voice
   track waiting for that song change is not played (a short one talks over the new song's start).
   0.7.1 - Spotify-quick Next:  {"song_id": ..., "rejoin": true}  -> the answer comes once the next song is on the
   air (up to 4 s): {"ok", "banner", "now": {id, artist, title}}. Fade your audio out the moment Next is pressed
   (~0.25 s), then reconnect to /stream?from=song (prebuffer ~1.2 s) - the new song plays from its first note.
   Skipped songs lose weight (x0.7); songs played through gain (+0.1).

5. SPLASH SCREENS (show one every time the app starts)
   GET /api/splash  ->  [ {name, size, mtime, url}, ... ]  in file-name order
   GET <url>           the image (url carries ?v=<mtime> so a replaced file refreshes)
   Round-robin: remember the last index on the device, show (last + 1) % count.
   The owner adds images by dropping them in C:\EWi\Trucker Radio\splash\ -
   agents should download new ones in the background for next time.

6. RECONNECT
   If the stream drops or stops moving for ~10 s, wait 2-3 s and dial in again.
   New connections get a 3 s burst so audio starts immediately.

7. PHONE APP (installable web app)
   /player is a full player with manifest (/manifest.webmanifest), icons (/icons/*)
   and a service worker (/sw.js). On https it installs like an app:
   Android Chrome "Install app", iPhone Safari Share -> "Add to Home Screen".

8. MESSAGE THE DJ (optional, Oct 2026)
   POST /api/message   Content-Type: application/json   {"name": "<optional>", "text": "<up to 400 chars>"}
   -> {"ok": true, "id": n, "status": "approved" | "pending" | "merged"}   or 400 / 429 {"error": "..."}
   Goes into the station's message inbox (moderation, expiry). The programming brain decides whether and
   when the DJ mentions it - a message never goes on the air directly. Rate-limited per listener.
   Song requests ("play me a Rush song") are queued by the station and announced right before the song;
   a later dedication from the same listener ("dedicate that to ...") joins that request ("merged").

9. WHERE THE LISTENER IS (optional, ask the listener first)
   POST /api/listener/location   {"lat": 43.07, "lon": -89.40, "name": "<optional>", "dev": "<device id>"}  -> {"ok": true}
   The phone player asks once (and says what is kept), then sends its position every 10 minutes while it
   listens. The DJ gets the nearest city; the point goes to the station's own map as the listener's route
   (kept 6 months, per device id - section 11) and tells the DJ who is on the move. Never shown to other
   listeners. PC agents that don't send this are placed by where they connect from (IP lookup, city level).

10. REQUEST A SONG (optional, Oct 2026)
   GET  /api/request/search?q=<artist / title words>
   -> {"enabled": true, "dedications": true, "results": [{"id": n, "artist": "...", "title": "...", "album": "...",
       "year": 1981, "ok": true | false, "why": "<why not right now, shown to the listener>"}]}
   POST /api/request   {"song_id": n, "name": "<optional>", "dedicate": "<optional>"}
   -> {"ok": true, "status": "queued", "plays_in": <songs before it>, "eta_sec": n, "message": "You're in line! ..."}
      or {"ok": true, "status": "pending", "message": "..."} (a name / dedication the station checks first)
      or 400 {"error": "<said to the listener: played recently / artist just played / limit / line full / off>"}
   The station's rules (Configuration > Requests) decide; the song goes into the queue and the DJ announces it
   right before it plays ("got a request for Brian Anderson - here's Rush"). Show "message" / "error" as is.

   Browsing like Spotify (phone player 1004.7, Oct 2026) - all GETs, rate-limited per address, each song with
   "ok" / "why" like the search:
   GET  /api/request/home                       -> {artists: [{key, name, cover}], recent: [song], genres: [{genre, n}]}
   GET  /api/request/artist?key=<artist_key>     -> {name, cover, songs, top: [song], albums: [{album_key, album, year, n, live, cover}]}
   GET  /api/request/album?key=<artist_key>&album=<album_key> -> {artist, album, year, cover, tracks: [song]}
   GET  /api/request/genre?g=<genre>             -> {genre, artists: [{key, name, cover, n}]}
   The search also returns "artists" and "albums" next to "results". cover = a song id: GET /api/art/<id>.

11. DEVICE ID (0.7.1) - no logins
   Make up a random ID once (a UUID), keep it on the device, and send it with EVERY call:
     header  X-Listener-Id: <id>          (8-64 letters, digits, dashes)
     and on the stream:  /stream?dev=<id>  (players that can't set headers on audio)
   The station names a device once (console Listeners screen, or the name the listener types in Message the DJ /
   Request / a road game) and that name follows the device to any network or city.

12. ROAD GAMES (0.7.1) - "every trucker's favorite game"
   /api/nowplaying carries "game" while a round is on (and for a minute or two after the answer):
   {"round": n, "game": "quote", "title": "Guess That Quote", "question": "<the quote>", "prompt": "Which movie is
    this line from?", "choices": ["A text", "B text", "C text", "D text"], "status": "live" | "revealed" | "closed",
    "my": <index this device picked or null>, "closes_in": <seconds until the DJ gives the answer, while live>,
    after the answer: "answer": <index>, "reveal": "<where it's from>", "right": ["Eddie", ...], "right_n": n, "n": n}
   Show a card: the question on top, four BIG buttons A-D, the countdown in a corner; after the answer mark the right
   one. POST /api/game/answer  {"round": n, "choice": 0-3, "name": "<optional>"}  -> {"ok": true} (change it any time
   while live) or 400 {"error": "this round is over"}.

13. UP NEXT, FAVORITES, MY DEVICES (0.9.36, Oct 18 2026 - the new player)
    GET  /api/upnext                     -> {items:[{id,artist,title,album,duration,request}], admin}
         the coming songs (the cued one first); request = who asked, or null. Read-only for listeners;
         the station, logged in (admin true), also gets log_id per item and may reorder / take out with
         POST /api/admin/log/move {id, before|after} and /api/admin/log/remove {id}.
    GET  /api/me/favs                    -> {items:[songs]}      POST /api/me/favs {song_id, on}
    GET  /api/me/fav?id=N                -> {fav: true|false}
    GET  /api/me/devices                 -> {linked, devices:[{dev,name,playing,me}]}
    POST /api/me/devices/code            -> {code:"123456"}   (lasts 10 minutes)
    POST /api/me/devices/link {code}     -> {ok, ...devices}   joins this device to the other one's group
    POST /api/me/devices/unlink | /api/me/devices/move (stop the group's other playing devices) | /api/me/devices/stop {dev}
    All need the X-Listener-Id header (the DEVICE ID, section 11). Favorites belong to the group once linked.
    A device told to stop finds it in its next GET /api/nowplaying: "cmd": {"cmd":"stop","by":"<device name>"}
    - stop playing and say "Moved to <by>". Players that poll /api/nowplaying must obey it (web page,
    Android app service, Windows player). Opening a player never takes over another device by itself.
